<?php
/**
 * Abstract service to manage Category
 */
interface Model_CategoryService
{
    /**
     * Fetch the top ten categories
     * 
     * @return array of Model_Entity_Category
     */
    public function getTopTenCategories();
    
    /**
     * Fetch all user categories
     * 
     * @param int $userID
     * @return array of Model_Entity_Category
     */
    public function getUserCategories($userID);
    
    /**
     * Retrieve all categories
     * 
     * @return array of Model_Entity_Category
     */
    public function getCategories();
    
    /**
     * Retrieve informations of a category by it's ID
     * 
     * @param Model_Entity_Category $category
     * @return Model_Entity_Category
     */
    public function getCategory(Model_Entity_Category $category);
    
    /**
     * Add a new category
     * 
     * @param Model_Entity_Category $category
     * @return void
     */
    public function addCategory(Model_Entity_Category $category);
    
    /**
     * Add a new user category
     * 
     * @param Model_Entity_Category $category
     * @return void
     */
    public function addUserCategory(Model_Entity_Category $category);
    
    /**
     * Update informatio of an existing user category
     * 
     * @param Model_Entity_Category $category
     * @return void
     */
    public function updateUserCategory(Model_Entity_Category $category);
    
    /**
     * Remove a category from it's owner
     * 
     * @param Model_Entity_Category $category
     * @return void
     */
    public function deleteUserCategory(Model_Entity_Category $category);
    
    /**
     * Remove an existing category
     * 
     * @param Model_Entity_Category $category
     * @return void
     */
    public function deleteCategory(Model_Entity_Category $category);
    
    /**
     * Search for feed matching search criteria based on category and
     * contents of name,url and description fields
     * If no criteria are specified it will return the entire list of Feeds
     * in the system
     * 
     * @param array $criteria an optional associative array 
     * @return Zend_Paginator_Adapter_Interface
     */
    public function searchCategories($criteria = null);
    
    /**
     * Set a given category as interesting for a given user 
     * 
     * @param int $catID
     * @param int $userID
     * @return void
     */
    public function setCategoryOfInterest($catID, $userID);
    
    /**
     * Unset a given category as interesting for a given user 
     * 
     * @param int $catID
     * @param int $userID
     * @return void
     */
    public function removeCategoryOfInterest($catID, $userID);
    
    /**
     * Retrieve the list of interesting categories for a given user
     * 
     * @param int $userID
     * @return array of Model_Entity_Category
     */
    public function getCategoriesOfInterest($userID);
}
